home *** CD-ROM | disk | FTP | other *** search
/ Visual Basic Source Code / Visual Basic Source Code.iso / vbsource / formatvb / readme.txt < prev    next >
Text File  |  1999-08-20  |  8KB  |  195 lines
  1.  
  2.                        FormatVB  Ver. 0.4
  3. August, 1999
  4. A program to reformat Visual Basic Source Code. 
  5.  
  6.  
  7. This program is a Win32 Console Application.  That means that it
  8. runs from the Command Line in the MS-DOS Window.  It also means
  9. that is has no Install procedure, no Uninstall procedure and does
  10. not alter the Registry in any manner.  Simply Unzip the Zip file
  11. into a directory on your Path and execute the program.  If you
  12. decide to remove it from your computer, simple delete it from the
  13. disk.
  14.  
  15. The objective of the Console Version of this program was to produce
  16. a program that is very fast, compact and simple for programmers to
  17. use and which can reformat large amounts of source code with one
  18. command in only a few minutes.  In addition, it is also powerful in
  19. its reformatting capabilities.  For example, it will reformat a
  20. single line Header for a Function or Sub into multiple lines.  It
  21. will remove extra blank lines between functions and will insert
  22. blank lines at strategic locations.  It will separate "For " and
  23. "With " groups, of specified size, by inserting a blank line before
  24. and after the groups.  The best way to appreciate what the program
  25. can do is to process some very poorly formatted Visual Basic code
  26. and with the code and then examine the output.
  27.  
  28. This version of the program does not overwrite the input source
  29. file.  The command line requires two parameters.  The first is the
  30. name of the source file and the second is the output file.  A
  31. future version will effectively reformat in place and will also
  32. have generic filename capabilities.  The program will then reformat
  33. all the BAS files, CLS files and FRM files in a directory with one
  34. command.
  35.  
  36. To execute the program, open a MS-DOS Window and at the command
  37. line type:
  38.  
  39.        FormatVB  inputFileName   outFileName  [options]
  40.  
  41. See the following reference page for the options.  To get started,
  42. you can try the /a option.  This option invokes all the
  43. functionality of the program.  So you would have:
  44.  
  45.        FormatVB   InputFilename    OutputFilename   /a
  46.  
  47. The source code that is feed to this program must be synthetically
  48. correct since there is no syntax checking within the program. 
  49. Please process only code that has been successfully compiled within
  50. Visual Basic.
  51.  
  52.  
  53. Protecting a Block of Code:
  54.  
  55. A block of code may be protected from reformatting by a pair of
  56. comments.  At the point where the protection is desired, enter a
  57. comment with the character string "$Protect" anywhere in the
  58. comment.  Then to return to formatting, enter a comment containing
  59. the character string "$Unprotect".  These keywords are not case
  60. sensitive; "$Protect" and "$PROTECT" are the same.  For example,
  61.  
  62.  
  63.         '-- $Protect    As of 08-20-1999
  64.             Code to be protected
  65.         '-- $Unprotect 
  66.  
  67. Two major advantages of the program is to enforce a consistent and
  68. very readable format for source code that is developed inhouse. 
  69. This reduces the cost of software maintenance very significantly. 
  70. Another major advantage is realized when you have to deal with code
  71. that is developed by others; weather it be the source code that is
  72. supplied with many of programming books, a purchased application or
  73. a sample application such as the Duwamish Books that is available
  74. from Microsoft.
  75.  
  76. Please note that this is Version number 0.4 of the program and
  77. treat it accordingly.  Don't bet the farm -- or even a bushel of
  78. corn on it.  Please make a backup copy of all source code to be
  79. processed before using the program.  Then, don't overlay any source
  80. code with the reformatted source code until the reformatted source
  81. code is loaded into the Visual Basic IDE and successfully compiled.
  82.  
  83. Included in the Zip file is a Sample.bas file.  This is just a
  84. sample input file.  Take a look at this file with Notepad, Wordpad,
  85. or some similar program, run it through the FormatVB program and
  86. then take a look at the Output that is produced.  This will give
  87. you a good idea of what the program does.  To process the sample
  88. input file, simply type:
  89.  
  90.          FormatVB   Sample.bas   Z1
  91.  
  92. at the DOS Prompt.  Delete Z1 when you are finished.  Note that
  93. there is no checking for overwriting of the output file.  Don't use
  94. a filename that is already in use unless you want to replace it.
  95.  
  96. This program is not shareware.  This program is not freeware.
  97. However, unregistered copies of the program may be freely shared
  98. with others.  Registered versions will be given functionality and
  99. features that does not currently exist and registered copies of the
  100. program may not be distributed.  It is anticipated that the
  101. registration fee will be $20.00 for individuals and $50.00 for
  102. companies and corporations.  The first 100 persons that provide
  103. useful feedback will be given registered copies at no cost.
  104.  
  105. I am very much interested in constructive feedback.  What do you
  106. like about the program?  What do you dislike about it?  If you run
  107. into any snags, I would appreciate receiving a snippet that
  108. demonstrates the problem; along with a brief description of the
  109. problem.  Please contact me via email at:
  110.  
  111.                       tn1@BellSouth.net
  112.  
  113.  
  114. Thank you,
  115.  
  116. Jim Holloman
  117.                             FormatVB 
  118.                    Reference Page for Options
  119.  
  120.  
  121.   Extended Formatting Options:
  122.  
  123.      These options provide for formatting beyond the basic
  124.      formatting.
  125.  
  126.      First of all, the /a option invokes all the extended
  127.      formatting options.  If you wish to use all the formatting
  128.      features, but still specify your own tab size or ForWith group
  129.      size you can do so by combinning the /t and /f options with
  130.      the /a option.  If a tabsize is not specified with the /t
  131.      option, then the default tab size of 3 will be used.  If a
  132.      ForWith group size is not specified with the /f option, then
  133.      the default of 6 for the "For " and "With " group size will be
  134.      used.
  135.  
  136.      It is generally recommended that the /a option be used to
  137.      invoke all the extended formatting options unless there is
  138.      some specific reason why all the options are not desired.
  139.  
  140.  
  141.      /a   - Invoke all the extended formatting options.
  142.  
  143.      /c   - Process Comments
  144.  
  145.             This option convents a stand-alone comment of form:
  146.  
  147.                'This is a comment
  148.  
  149.             to
  150.  
  151.                '-- This is a comment
  152.  
  153.      /Fnn - Group size in regards to "For " and "With " groups.
  154.  
  155.             "For " and "With " groups, when they are larger than nn
  156.             lines, will be separated from adjacent code with blank
  157.             lines.
  158.  
  159.             The default for 'nn' is 6.
  160.  
  161.             This option will put a blank line before and after a
  162.             "With " block or a "For " block that contains more than
  163.             the specified number of lines.  However, if the block 
  164.             is immediately proceeded by a comment, then a blank
  165.             line will not be inserted before the block.
  166.  
  167.      /H   - Process Block Headers
  168.             This option will cause Block Headers (Public Function,
  169.             Private Sub, etc.) that exceed 72 characters in length
  170.             and have more than one parameter to be split into
  171.             multiple lines.
  172.  
  173.      /I   - Split single line "If " into two lines
  174.  
  175.             This option will cause single line "If " statements of
  176.             the format:
  177.  
  178.                If a = b then c = d
  179.  
  180.             to be converted to two lines of the format:
  181.  
  182.                If a = b then _
  183.                   c = d
  184.  
  185.      /Tn  - Tab Size Setting, i.e. /t4
  186.  
  187.             This option specifies the tab size, if something other
  188.             than the default of 3 is desired.
  189.  
  190.      /W   - Process WinAPI Declares
  191.  
  192.             This option will cause WinAPI Declares that have
  193.             multiple parameters to be split into multiple lines.
  194.  
  195.